Amazon IVSをAWS CLIで操作してみた

Amazon Interactive Video Service (Amazon IVS)をAWS CLIで操作してみました。IVS自体が非常にシンプルにライブ配信ができるぶん、AWS CLIでも非常にシンプルに使える印象です。

#AWSメディアサービス

#AWS CLI

#AWS

清水俊也

2020.07.31

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

はじめに

清水です。先日発表されたAWSのフルマネージドなライブストリーミングソリューションであるAmazon Interactive Video Service (Amazon IVS)をAWS CLIで操作しChannelなどリソース作成、ライブ配信中のステータス確認、そしてChannelの削除まで行なってみたのでまとめてみます。

なおAWS CLIの環境はv2の現時点での最新版を使用しました。具体的には以下の環境となります。

% aws --version
aws-cli/2.0.36 Python/3.7.4 Darwin/19.6.0 exe/x86_64

IVS用のコマンドはaws ivsではじまるものとして準備されています。

ivs — AWS CLI 2.0.36 Command Reference

現時点では以下の18個のコマンドから構成されています。

batch-get-channel
batch-get-stream-key
create-channel
create-stream-key
delete-channel
delete-stream-key
get-channel
get-stream
get-stream-key
list-channels
list-stream-keys
list-streams
list-tags-for-resource
put-metadata
stop-stream
tag-resource
untag-resource
update-channel

本エントリではすべてのコマンドは扱いませんが、IVSのリソースとなるChannelを作成、ライブ配信中のステータス確認、Channel削除までをAWS CLIで操作してみたいと思います。

Channelの作成

まずChannelの作成はaws ivs create-channelコマンドで行います。

create-channel — AWS CLI 2.0.36 Command Reference

% aws ivs create-channel --name <value>

以下、実行例です。Channelリソースの名称としてcli-test-channelを引数に渡しました。

 % aws ivs create-channel --name "cli-test-channel" --region us-west-2 
{
    "channel": {
        "arn": "arn:aws:ivs:us-west-2:123456789012:channel/XvXXXXXXXXIQ",
        "name": "cli-test-channel",
        "latencyMode": "LOW",
        "type": "STANDARD",
        "ingestEndpoint": "28XXXXXXXXdb.global-contribute.live-video.net",
        "playbackUrl": "https://28XXXXXXXXdb.us-west-2.playback.live-video.net/api/video/v1/us-west-2.123456789012.channel.XvXXXXXXXXIQ.m3u8",
        "tags": {}
    },
    "streamKey": {
        "arn": "arn:aws:ivs:us-west-2:123456789012:stream-key/ZqXXXXXXXXpr",
        "value": "sk_us-west-2_ZqXXXXXXXXpr_VjXXXXXXXXXXXXXXXXXXXXXXXXXXw1",
        "channelArn": "arn:aws:ivs:us-west-2:123456789012:channel/XvXXXXXXXXIQ",
        "tags": {}
    }
}

ちなみに、引数なしで実行できるかな？（いや、エラー出るよなぁ）と実行してみたら、エラーも発生せずChannelリソースが作成できました。nameは空欄となっているようです。

% aws ivs create-channel --region us-west-2 
{
    "channel": {
        "arn": "arn:aws:ivs:us-west-2:123456789012:channel/U5XXXXXXXXBZ",
        "name": "",
        "latencyMode": "LOW",
        "type": "STANDARD",
        "ingestEndpoint": "28XXXXXXXXdb.global-contribute.live-video.net",
        "playbackUrl": "https://28XXXXXXXXdb.us-west-2.playback.live-video.net/api/video/v1/us-west-2.123456789012.channel.U5XXXXXXXXBZ.m3u8",
        "tags": {}
    },
    "streamKey": {
        "arn": "arn:aws:ivs:us-west-2:123456789012:stream-key/JiXXXXXXXXZT",
        "value": "sk_us-west-2_JiXXXXXXXXZT_8wXXXXXXXXXXXXXXXXXXXXXXXXXXUx",
        "channelArn": "arn:aws:ivs:us-west-2:123456789012:channel/U5XXXXXXXXBZ",
        "tags": {}
    }
}

Channelの一覧表示

Channelの一覧表示がaws ivs list-channelsコマンドで行えます。

list-channels — AWS CLI 2.0.36 Command Reference

% aws ivs list-channels

以下が実行結果です。Channelは3つある状態です。（2つがaws ivs create-channelで作成したもの、1つは先のエントリでマネジメントコンソールから作成したものとなります。）

% aws ivs list-channels --region us-west-2 
{
    "channels": [
        {
            "arn": "arn:aws:ivs:us-west-2:123456789012:channel/U5XXXXXXXXBZ",
            "name": "",
            "latencyMode": "LOW",
            "tags": {}
        },
        {
            "arn": "arn:aws:ivs:us-west-2:123456789012:channel/PuXXXXXXXXPi",
            "name": "ZoomLiveStreamingIVSChannel",
            "latencyMode": "LOW",
            "tags": {}
        },
        {
            "arn": "arn:aws:ivs:us-west-2:123456789012:channel/XvXXXXXXXXIQ",
            "name": "cli-test-channel",
            "latencyMode": "LOW",
            "tags": {}
        }
    ]
}

Channel情報の個別表示

続いてChannel情報の個別表示です、aws ivs get-channelコマンドで実行します。

get-channel — AWS CLI 2.0.36 Command Reference

% aws ivs get-channel --arn <value>

引数としてはChannelのARNが必要です。Channel作成時のレスポンスやlist-channelsコマンドの実行結果からARNを取得しましょう。今回はシェル内で変数CHANNEL_ARNに格納しておきます。

% CHANNEL_ARN="arn:aws:ivs:us-west-2:123456789012:channel/XvXXXXXXXXIQ"
% echo ${CHANNEL_ARN}
arn:aws:ivs:us-west-2:123456789012:channel/XvXXXXXXXXIQ

以下が実行結果です。一覧表示のlist-channelsコマンドよりも詳細な情報が取得できていることがわかります。

 % aws ivs get-channel --arn ${CHANNEL_ARN} --region us-west-2 
{
    "channel": {
        "arn": "arn:aws:ivs:us-west-2:123456789012:channel/XvXXXXXXXXIQ",
        "name": "cli-test-channel",
        "latencyMode": "LOW",
        "type": "STANDARD",
        "ingestEndpoint": "28XXXXXXXXdb.global-contribute.live-video.net",
        "playbackUrl": "https://28XXXXXXXXdb.us-west-2.playback.live-video.net/api/video/v1/us-west-2.123456789012.channel.XvXXXXXXXXIQ.m3u8",
        "tags": {}
    }
}

この情報から、配信エンコーダに設定する情報のうちインジェスト用のEndpoint、また動画プレイヤーに設定するPlayback URLを得ることができます。以下のようにシェル変数に格納しておきました。

% INGEST_ENDPOINT=$(aws ivs get-channel --arn ${CHANNEL_ARN} --region us-west-2  --query channel.ingestEndpoint --output text)
% echo ${INGEST_ENDPOINT}
28XXXXXXXXdb.global-contribute.live-video.net
% INGEST_SERVER="rtmps://"${INGEST_ENDPOINT}"/app/"
% echo ${INGEST_SERVER}
rtmps://28XXXXXXXXdb.global-contribute.live-video.net/app/

% PLAYBACK_URL=$(aws ivs get-channel --arn ${CHANNEL_ARN} --region us-west-2  --query channel.playbackUrl --output text)
% echo ${PLAYBACK_URL}
https://28XXXXXXXXdb.us-west-2.playback.live-video.net/api/video/v1/us-west-2.123456789012.channel.XvXXXXXXXXIQ.m3u8

ストリームキー情報の表示

配信エンコーダに設定が必要なストリームキー情報はaws ivs list-stream-keysとaws ivs get-stream-keyコマンドで取得します。

aws ivs list-stream-keysコマンドでは、ChannelのARNを引数にとります。

% aws ivs list-stream-keys --channel-arn <value>

aws ivs get-stream-keyコマンドではStream KeyのARNを引数にとります。

% aws ivs get-stream-key --arn <value>

実際の例で確認してみましょう。まずはaws ivs list-stream-keysの実行です。ここではCahnnelのARNを引数に渡します。

% aws ivs list-stream-keys --channel-arn ${CHANNEL_ARN} --region us-west-2 
{
    "streamKeys": [
        {
            "arn": "arn:aws:ivs:us-west-2:123456789012:stream-key/ZqXXXXXXXXpr",
            "channelArn": "arn:aws:ivs:us-west-2:123456789012:channel/XvXXXXXXXXIQ",
            "tags": {}
        }
    ]
}

streamKeys[0].arnでStream KeyのARNを得ることができます。これもシェルの変数に格納しておきます。

% STREAMKEY_ARN=$(aws ivs list-stream-keys --channel-arn ${CHANNEL_ARN} --query 'streamKeys[0].arn' --region us-west-2  --output text)
% echo ${STREAMKEY_ARN}
arn:aws:ivs:us-west-2:123456789012:stream-key/ZqXXXXXXXXpr

続いてaws ivs get-stream-keyコマンドをStream KeyのARNを引数に実行します。

% aws ivs get-stream-key --arn ${STREAMKEY_ARN}  --region us-west-2                                                                   {
    "streamKey": {
        "arn": "arn:aws:ivs:us-west-2:123456789012:stream-key/ZqXXXXXXXXpr",
        "value": "sk_us-west-2_ZqXXXXXXXXpr_VjXXXXXXXXXXXXXXXXXXXXXXXXXXw1",
        "channelArn": "arn:aws:ivs:us-west-2:123456789012:channel/XvXXXXXXXXIQ",
        "tags": {}
    }
}

このstreamKey.valueが配信エンコーダに設定するストリームキーになります。以下でシェル変数に格納しておきます。

% STREAM_KEY=$(aws ivs get-stream-key --arn ${STREAMKEY_ARN} --query streamKey.value --region us-west-2  --output text)
% echo ${STREAM_KEY}
sk_us-west-2_ZqXXXXXXXXpr_VjXXXXXXXXXXXXXXXXXXXXXXXXXXw1

配信ステータスの確認

Channelを作成し、また配信に必要な情報がAWS CLIで収集できました。

確認しておくと、配信エンコーダに設定するIngest ServerとStream keyはシェル変数INGEST_SERVERとSTREAM_KEYに格納されています。

% echo  ${INGEST_SERVER}
rtmps://28XXXXXXXXdb.global-contribute.live-video.net/app/
% echo ${STREAM_KEY}
sk_us-west-2_ZqXXXXXXXXpr_VjXXXXXXXXXXXXXXXXXXXXXXXXXXw1

再生プレイヤーに設定するPlayback URLはシェル変数PLAYBACK_URLに格納されています。

 % echo ${PLAYBACK_URL}
https://28XXXXXXXXdb.us-west-2.playback.live-video.net/api/video/v1/us-west-2.123456789012.channel.XvXXXXXXXXIQ.m3u8

この情報で、実際に配信を開始してみます。配信中のステータスはaws ivs list-streams、aws ivs get-streamコマンドで取得できます。

aws ivs list-streamsコマンドはARNなどの引数は必要としません。

% aws ivs list-streams

aws ivs get-streamコマンドではChannelのARNを引数に渡す必要があります。

aws ivs get-stream --channel-arn <value>

以下、実際の実行例です。

% aws ivs list-streams --region us-west-2
{
    "streams": [
        {
            "channelArn": "arn:aws:ivs:us-west-2:123456789012:channel/XvXXXXXXXXIQ",
            "state": "LIVE",
            "health": "HEALTHY",
            "viewerCount": 2,
            "startTime": "2020-07-31T14:29:54+00:00"
        }
    ]
}

aws ivs get-streamコマンドではplaybackUrlまで取得が可能です。

 % aws ivs get-stream --channel-arn ${CHANNEL_ARN} --region us-west-2 
{
    "stream": {
        "channelArn": "arn:aws:ivs:us-west-2:123456789012:channel/XvXXXXXXXXIQ",
        "playbackUrl": "https://28XXXXXXXXdb.us-west-2.playback.live-video.net/api/video/v1/us-west-2.123456789012.channel.XvXXXXXXXXIQ.m3u8",
        "startTime": "2020-07-31T14:29:54+00:00",
        "state": "LIVE",
        "health": "HEALTHY",
        "viewerCount": 2
    }
}

なお、ライブ配信を停止している（配信エンコーダを停止している）状態の各コマンドの実行結果は下記のようになりました。aws ivs list-streamsは空要素で実行結果を返すのに対し、aws ivs get-stream`はエラーを返します。

% aws ivs list-streams --region us-west-2
{
    "streams": []
}

% aws ivs get-stream --channel-arn ${CHANNEL_ARN} --region us-west-2

An error occurred (ChannelNotBroadcasting) when calling the GetStream operation: ivs.ChannelNotBroadcasting: Channel: arn:aws:ivs:us-west-2:123456789012:channel/XvXXXXXXXXIQ is not currently online

Channelの削除

ライブ配信終了後のChannelリソース削除は、aws ivs delete-channelで行います。

delete-channel — AWS CLI 2.0.36 Command Reference

引数としてChannelのARNを渡します。なお実行時の戻り値はなしのとのことです。

% aws ivs  delete-channel --arn <value>

実際に削除する前に、aws ivs list-channelsとaws ivs get-channelコマンドで状況を確認しておきます。

% aws ivs list-channels --region us-west-2 --profile shimizu.toshiya
{
    "channels": [
        {
            "arn": "arn:aws:ivs:us-west-2:123456789012:channel/U5XXXXXXXXBZ",
            "name": "",
            "latencyMode": "LOW",
            "tags": {}
        },
        {
            "arn": "arn:aws:ivs:us-west-2:123456789012:channel/PuXXXXXXXXPi",
            "name": "ZoomLiveStreamingIVSChannel",
            "latencyMode": "LOW",
            "tags": {}
        },
        {
            "arn": "arn:aws:ivs:us-west-2:123456789012:channel/XvXXXXXXXXIQ",
            "name": "cli-test-channel",
            "latencyMode": "LOW",
            "tags": {}
        }
    ]
}

% aws ivs get-channel --arn ${ARN} --region us-west-2 --profile shimizu.toshiya
{
    "channel": {
        "arn": "arn:aws:ivs:us-west-2:123456789012:channel/XvXXXXXXXXIQ",
        "name": "cli-test-channel",
        "latencyMode": "LOW",
        "type": "STANDARD",
        "ingestEndpoint": "28XXXXXXXXdb.global-contribute.live-video.net",
        "playbackUrl": "https://28XXXXXXXXdb.us-west-2.playback.live-video.net/api/video/v1/us-west-2.123456789012.channel.XvXXXXXXXXIQ.m3u8",
        "tags": {}
    }
}

削除を実行します。実行結果の出力は特にありません。

% aws ivs get-channel --arn ${ARN} --region us-west-2 --profile shimizu.toshiya

削除後に、もういちど状況を確認します。

 % aws ivs list-channels --region us-west-2 --profile shimizu.toshiya           {
    "channels": [
        {
            "arn": "arn:aws:ivs:us-west-2:123456789012:channel/U5XXXXXXXXBZ",
            "name": "",
            "latencyMode": "LOW",
            "tags": {}
        },
        {
            "arn": "arn:aws:ivs:us-west-2:123456789012:channel/PuXXXXXXXXPi",
            "name": "ZoomLiveStreamingIVSChannel",
            "latencyMode": "LOW",
            "tags": {}
        }
    ]
}

% aws ivs get-channel --arn ${ARN} --region us-west-2 --profile shimizu.toshiya

An error occurred (ResourceNotFoundException) when calling the GetChannel operation: ivs.ResourceNotFoundException: Resource: arn:aws:ivs:us-west-2:123456789012:channel/XvXXXXXXXXIQ not found

Channel名称cli-test-channelについては削除されていることが確認できました。aws ivs get-channelコマンドについてはエラーとなりますね。

まとめ

Amazon Interactive Video Service (Amazon IVS)をAWS CLIで操作、Channelの作成から配信中のステータス確認、そしてChannelの削除までを行なってみました。IVSが非常にシンプルにライブ配信ができるぶん、AWS CLIでも非常にシンプルに使えるなぁという印象です。Amazon IVSのその他の細かな機能についても、AWS CLIでの実現含め追って確認していきたいと思います。